Skip to content

feat(plugin-js,plugin-simplicity): add no-mixed-libraries and no-reinvented-helper - #97

Open
luoling8192 wants to merge 2 commits into
alint-dev:mainfrom
luoling8192:luoling8192/feat/dependency-hygiene-rules
Open

luoling8192 wants to merge 2 commits into
alint-dev:mainfrom
luoling8192:luoling8192/feat/dependency-hygiene-rules

Conversation

@luoling8192

Copy link
Copy Markdown

Summary

This PR adds two model-backed rules for dependency hygiene. ESLint no-restricted-imports can ban a known library, but it cannot find two libraries that do the same job, or a helper that a dependency already exports. A model can.

  • js/no-mixed-libraries reports the imports of a library when the workspace also uses another library for the same job, for example zod and valibot.
  • simplicity/no-reinvented-helper reports a small helper when a utility library that the repository already depends on exports the same function, for example a local clamp next to es-toolkit.

Both rules started in the moeru-ai/airi monorepo, which uses one library for each job by policy. This PR moves them here in a general form: the AIRI package names and libraries are now options. Neither rule is in a recommended preset.

Change map

Module Before After Description
plugin-js No workspace-wide dependency rule no-mixed-libraries Reads the external imports of every JS, TS, and Vue file once per run, and makes one model call to group packages that do the same job. Reports only in the linted files
plugin-simplicity no-duplicated-helper, no-needless-helper Also no-reinvented-helper Reuses the small-helper index and settings.simplicity. One model call per file that has a helper
plugin-simplicity shared helpers ctx: RuleContext ctx: RuleContext<readonly unknown[]> This is the first simplicity rule with options. The helpers do not read options, so behavior does not change

js/no-mixed-libraries

  1. It lists every *.{ts,tsx,mts,cts,js,jsx,mjs,cjs,vue} file with @alint-js/tools-fs, and reads the package names with a text scan of static, side-effect, dynamic, and require imports. Packages that a workspace package.json names, @types/*, and built-in modules are left out.
  2. It sends one line per package (file count and the directories that import it most) to the model, one time for each run. The review is shared through ctx.src, the same key that the simplicity index uses.
  3. It drops a group that names a package no file imports, and a group that an allow set covers. A preferred package overrides the canonical package that the model chose.
  4. It reports each import of a replaced package in the linted file.

cache: false, because the verdict depends on every file in the workspace. It uses onTargetFile rather than onTargetProject, so it works in a config item that has files.

simplicity/no-reinvented-helper

  1. It takes libraries (at least one) from its options.
  2. It loads each library from the linted workspace and reads its runtime export names. require.resolve rejects a package whose exports map has only an import condition, so the rule then finds the manifest in the node_modules directories that Node searches.
  3. It sends the export names and the small helpers of the file to the model.
  4. It drops a finding that names a helper outside the file, a library outside the options, or an export that the library does not have.

It respects settings.simplicity.judge and ignores. It uses the core cache with the prompt as cacheKey. A library upgrade that adds an export reaches a cached file only after the file or the options change. The README states this.

Boundaries and risks

Invariant or boundary Failure mode Protection Evidence or gap
A finding points at real code The model invents a package, helper, library, or export Every name is checked against the usage index, the helper index, the options, or the loaded exports Unit tests for each kind of invented name
One model call per run for no-mixed-libraries A call for every linted file The review is memoized on ctx.src Unit test: three files, one request
Loading a library runs its code A library with top-level side effects Only the libraries in the options are loaded. The README says to list only trusted libraries By design
Import scan accuracy A string that looks like an import, in a comment or a string literal None. It can add a package to the usage list, but a report also needs a model group Accepted, explained in a code comment
Large workspaces The usage prompt grows with the number of external packages One line per package Not measured

Verification

pnpm -F @alint-js/plugin-js exec vitest run           7 files, 21 tests passed
pnpm -F @alint-js/plugin-simplicity exec vitest run   7 files, 107 tests passed
pnpm typecheck                                        passed
pnpm lint                                             passed
cspell (changed files)                                no new issues

The rule tests run the real rule against a temporary workspace and answer the model call from a local HTTP server, as the existing no-needless-helper tests do. The no-reinvented-helper workspace has an ESM-only library with an import-only exports map.

Not verified:

  • These rules have not run against a real model in this repository. An earlier version ran in moeru-ai/airi: no-mixed-libraries reported 47 imports in four AIRI workspaces, and all groups matched a manual audit (for example zod to valibot, localforage to unstorage). It missed async-mutex to the es-toolkit Mutex. no-reinvented-helper reported 4 helpers in 8 sample files, all correct (sleep and clamp), with no false positive in 3 control files. The prompts here are the same, but the code changed, so treat these numbers as a hint, not as evidence for this PR.
  • Cost on a large workspace.

🤖 Generated with Claude Code

luoling8192 and others added 2 commits November 9, 2026 02:15
The rule reports the imports of a library when the workspace also uses another library for the same job, for example zod and valibot. It collects the external package imports of every source file once per run, and asks the model one time to group the packages that do the same job. A group that names a package no file imports, or that an allow set covers, is dropped. A preferred package becomes the canonical member of its group. Diagnostics go only to the linted files.

The rule is registered but not in recommended, because it reads the whole workspace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rule reports a small helper when a utility library that the repository already depends on exports the same function. The libraries come from the rule options. The rule loads each one from the linted workspace to read its real export names, and drops a finding that names an unknown helper, library, or export. It uses the shared index of small helpers and the settings.simplicity options.

The shared helpers now accept a rule context with options, because this is the first simplicity rule that takes options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant